docs: refactoring doc scripts #1743
Conversation
googlebot
added
the
cla: yes
|
Does this resolve #1618? |
|
@stephenplusplus I think this should be good to go if you care to take a look! |
| @@ -21,7 +21,24 @@ before_script: | |||
| fi | |||
| script: "node ./scripts/build.js" | |||
| after_success: | |||
| - if [ $IS_PUSH_TO_MASTER ]; then | |||
| node ./scripts/build-docs.js; | |||
| - if [ $IS_PUSH_TO_MASTER && "${TRAVIS_JOB_NUMBER}" == *1 ]; then | |||
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
|
If this resolves #1618, can you outline what the workflow is for updating the docs website is and pop it in CONTRIBUTING? |
|
@stephenplusplus I've updated the CONTRIBUTING guide, you can preview it on my fork. |
|
Thank you, the write up is awesome. But, is it possible to have a command that does all that for us, right up until the git push? |
|
So you want to automate this $ git submodule add -b gh-pages git@github.com:GoogleCloudPlatform/google-cloud-node.git
$ rm -rf docs/json
$ npm run docs google-cloud 0.43.0
$ cp -rf docs/json/* gh-pages/json
$ cp docs/manifest.json gh-pages
$ cd gh-pages
$ git add .
$ git commit -m 'Update docs for google-cloud 0.43.0 [ci skip]'? |
|
Yeah, one command and then manual push to origin. |
|
Done, PTAL. |
| Finally the last thing to do is cleanup the submodule we created to copy over the JSON. | ||
|
|
||
| ```sh | ||
| $ git submodule deinit -f gh-pages |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
Yep |
|
|
||
| All of the documentation is powered by JSDoc, we parse it into JSON and feed it to an [application](https://github.com/GoogleCloudPlatform/gcloud-common/tree/master/site) built in Angular. Hopefully our CI builds and updates the documentation for each successful merge to master, but if for whatever reason a manual update is required please refer to the following steps. | ||
|
|
||
| We can build the documentation using the `npm run prepare-docs` command. This command optionally accepts two parameters. |
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
closes #1618
This essentially let's us generate JSON for arbitrary releases since we often can't count on Travis to do this in a timely fashion.
Example:
The script does not automatically commit/push anymore however. This will be up to the user to manually do (I still need to tie this into our
.travis.yml) and they'll also have to clean up the submodule used to push the docs.